<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/2000/REC-xhtml1-20000126/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
        <title>Log4j Bridge</title>
        <link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
        <link rel="stylesheet" type="text/css" media="print" href="css/print.css" />

    </head>
    <body>
        <script>
            prefix = '';
        </script>

        <script src="templates/header.js"></script>
        <div id="left">
            <script src="templates/left.js"></script>
        </div>
        <div id="right">
            <script src="templates/right.js"></script>
        </div>
        <div id="content">


            <h1>Bridging legacy APIs</h1>

            <p>Often, some of the components you depend on rely on a logging API
                other than SLF4J. These components presumably will not switch to
                SLF4J in the near future. SLF4J ships with several bridging modules
                which redirect calls to log4j, JCL and j.u.l APIs to behave as if
                they were made to the SLF4J API. The figure below illustrates the
                idea.
            </p>

            <p></p>
            <p></p>


            <p><a href="images/bridging.png">
                    <img src="images/bridging.png" alt="click to enlarge" width="800"/>
                </a></p>

            <p>
            </p>

            <h2><a name="jcl-over-slf4j" href="#jcl-over-slf4j">Gradual migration to
                    SLF4J from Jakarta Commons Logging (JCL)</a></h2>

            <h2><em>jcl-over-slf4j.jar</em></h2>

            <p>To ease migration to SLF4J from JCL, recent SLF4J distributions
                include the jar file <em>jcl-over-slf4j.jar</em>. This jar file is
                intended as a drop-in replacement for JCL version 1.1.1. It
                implements the public API of JCL but using SLF4J underneath, hence
                the name "JCL over SLF4J."
            </p>

            <p>Our JCL over SLF4J implementation will allow you to migrate to
                SLF4J gradually, especially if some of the libraries your software
                depends on continue to use JCL for the foreseeable future. You can
                immediately enjoy the benefits of SLF4J's reliability and preserve
                backward compatibility at the same time. Just replace
                <em>commons-logging.jar</em> with
                <em>jcl-over-slf4j.jar</em>. Subsequently, the selection of the
                underlying logging system will be done by SLF4J instead of JCL but
                without the class loader headaches. The underlying logging system
                can be any of NOP, simple, jdk14 logging, log4j or logback. Any
                existing dependency on commons-logging therefore becomes less of an
                issue.
            </p>

            <h2><em>slf4j-jcl.jar</em></h2>

            <p>Some of our users after having switched to SLF4J API realize that
                in some contexts the use of JCL is mandatory and their use of SLF4J
                can be a problem. For this uncommon but important case, SLF4J offers
                a JCL binding, found in the file <em>slf4j-jcl.jar</em>. The JCL
                binding will delegate all logging calls made through SLF4J API to
                JCL. Thus, if for some reason an existing application <em>must</em>
                use JCL, your part of that application can still code against the
                SLF4J API in a manner transparent to the larger application
                environment. Your choice of SLF4J API will be invisible to the rest
                of the application which can continue to use JCL.
            </p>

            <h2><em>jcl-over-slf4j.jar</em> should not be confused with
                <em>slf4j-jcl.jar</em></h2>


            <p>JCL-over-SLF4J, i.e. <em>jcl-over-slf4j.jar</em>, comes in handy
                in situations where JCL needs to be supported for backward
                compatibility reasons. It can be used to fix problems associated
                with JCL, without necessarily adopting the SLF4J API, a decision
                which can be deferred to a later time.
            </p>

            <p>On the other hand, <em>slf4j-jcl.jar</em> is useful
                <strong>after</strong> you have already adopted the SLF4J API for
                your component which needs to be embedded in a larger application
                environment where JCL is a formal requirement. Your software
                component can still use SLF4J API without disrupting the larger
                application. Indeed, <em>slf4j-jcl.jar</em> will delegate all
                logging decisions to JCL so that the dependency on SLF4J API by your
                component will be transparent to the larger whole.
            </p>

            <p>Please note that <em>jcl-over-slf4j.jar</em> and
                <em>slf4j-jcl.jar</em> cannot be deployed at the same time. The
                former jar file will cause JCL to delegate the choice of the logging
                system to SLF4J and the latter jar file will cause SLF4J to delegate
                the choice of the logging system to JCL, resulting in an infinite
                loop.
            </p>


            <h2><a name="log4j-over-slf4j" href="#log4j-over-slf4j">Log4j over
                    SLF4J</a></h2>

            <p>SLF4J ship with a module called <em>log4j-over-slf4j</em>.  It
                allows log4j users to migrate existing applications to SLF4J without
                changing <em>a single line of code</em> but simply by replacing the
                <em>log4j.jar</em> file with <em>log4j-over-slf4j.jar</em>, as
                described below.
            </p>

            <h3>How does it work?</h3>

            <p>The log4j-over-slf4j module contains replacements of most widely
                used log4j classes, namely <code>org.apache.log4j.Category</code>,
                <code>org.apache.log4j.Logger</code>,
                <code>org.apache.log4j.Priority</code>,
                <code>org.apache.log4j.Level</code>,
                <code>org.apache.log4j.MDC</code>, and
                <code>org.apache.log4j.BasicConfigurator</code>. These replacement
                classes redirect all work to their corresponding SLF4J classes.
            </p>

            <p>To use log4j-over-slf4j in your own application, the first step
                is to locate and then to replace <em>log4j.jar</em> with
                <em>log4j-over-slf4j.jar</em>. Note that you still need an SLF4J
                binding and its dependencies for log4j-over-slf4j to work properly.
            </p>

            <p>In most situtations, replacing a jar file is all it takes in
                order to migrate from log4j to SLF4J.
            </p>

            <p>Note that as a result of this migration, log4j configuration
                files will no longer be picked up. If you need to migrate your
                log4j.properties file to logback, the <a
                    href="http://logback.qos.ch/translator/">log4j translator</a> might
                be of help. For configuring logback, please refer to <a
                    href="http://logback.qos.ch/manual/index.html">its manual</a>.
            </p>

            <p>We are happy to report that several applications are
                successfully using log4j-over-slf4j in production.
            </p>


            <h3>When does it not work?</h3>

            <p>The <em>log4j-over-slf4j</em> module will not work when the
                application calls log4j components that are not present in the
                bridge.  For example, direct references to log4j appenders,
                filters or PropertyConfigurator are not supported by
                log4j-over-slf4j.  While the number of cases where
                log4j-over-slf4j is insufficient is not completely negligible, in
                the vast majority of cases where log4j is configured through a
                configuration file, be it <em>log4j.properties</em> or
                <em>log4j.xml</em>, log4j-over-slf4j is enough in order to migrate
                your application to SLF4J.
            </p>

            <h3>What about the overhead?</h3>

            <p>There overhead of using log4j-over-slf4j instead of log4j
                directly is relatively small. Given that log4j-over-slf4j
                immediately delegates all work to SLF4J, the CPU overhead should be
                negligible, in the order of a few <em>nanoseconds</em>. There is a
                memory overhead corresponding to an entry in a hashmap per logger,
                which should be usually acceptable even for very large applications
                consisting of several thousand loggers.  Moreover, if you choose
                logback as your underlying logging system, and given that logback is
                both much faster and more memory-efficient than log4j, the gains
                made by using logback should compensate for the overhead of using
                log4j-over-slf4j instead of log4j directly.
            </p>

            <h3>log4j-over-slf4j.jar and slf4j-logj12.jar cannot be present
                simultaneously
            </h3>

            <p>The presence of <em>slf4j-logj12.jar</em>, that is the log4j
                binding for SLF4J, will force all SLF4J calls to be delegated to
                log4j. The presence of <em>log4j-over-slf4j.jar</em> will in turn
                delegate all log4j API calls to their SLF4J equivalents. If both are
                present simulatenously, slf4j calls will be delegated to log4j, and
                log4j calls redirected to SLF4j, resulting in an endless recursion.
            </p>

            <h2><a name="jul-to-slf4j" href="jul-to-slf4j">JUL to SLF4J</a></h2>

            <p>The jul-to-slf4j module includes a jul handler, namely
                SLF4JBridgeHandler, that routes all incoming jul records to the
                SLF4j API. See also <a
                    href="api/org/slf4j/bridge/SLF4JBridgeHandler.html">SLF4JBridgeHandler
                    javadocs</a>. Contrary to other bridging modules such as
                jcl-over-slfj and log4j-over-slf4h, which re-implement JCL and
                respectively log4j, the jul-to-slf4j modules does not re-implement
                the java.util.logging package because packages under the java.*
                namespace cannot be replaced.
            </p>

            <h3>jul-to-slf4j.jar and slf4j-jdk14.jar cannot be present
                simultaneously
            </h3>

            <p>The presence of slf4j-jdk14.jar, that is the jul binding for
                SLF4J, will force SLF4J calls to be delegated to jul. On the other
                hand, the presence of jul-to-slf4j.jar, plus the installation of
                SLF4JHandler, by invoking "SLF4JHandler.install()" will route jul
                records to SLF4J. Thus, if both jar are present simultanesouly (and
                SLF4JHandler is installed), slf4j calls will be delegated to jul and
                jul records will be routed to SLF4J, resulting in an endless
                recursion.
            </p> 


            <script
            src="templates/footer.js"></script> </div> </body> </html>
